<!-------- @HEADER
 !
 ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !
 !  Zoltan Toolkit for Load-balancing, Partitioning, Ordering and Coloring
 !                  Copyright 2012 Sandia Corporation
 !
 ! Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
 ! the U.S. Government retains certain rights in this software.
 !
 ! Redistribution and use in source and binary forms, with or without
 ! modification, are permitted provided that the following conditions are
 ! met:
 !
 ! 1. Redistributions of source code must retain the above copyright
 ! notice, this list of conditions and the following disclaimer.
 !
 ! 2. Redistributions in binary form must reproduce the above copyright
 ! notice, this list of conditions and the following disclaimer in the
 ! documentation and/or other materials provided with the distribution.
 !
 ! 3. Neither the name of the Corporation nor the names of the
 ! contributors may be used to endorse or promote products derived from
 ! this software without specific prior written permission.
 !
 ! THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
 ! EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 ! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 ! PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
 ! CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 ! EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 ! PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 ! PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 ! LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 ! NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 ! SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 !
 ! Questions? Contact Karen Devine	kddevin@sandia.gov
 !                    Erik Boman	egboman@sandia.gov
 !
 ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !
 ! @HEADER
-------> 
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="GENERATOR" content="Mozilla/4.76 [en] (X11; U; Linux 2.4.2-2smp i686) [Netscape]">
  <meta name="sandia.approval_type" content="formal">
  <meta name="sandia.approved" content="SAND2007-4748W">
  <meta name="author" content="Zoltan PI">

   <title>Zoltan User's Guide:  General Zoltan Interface</title>
</head>
<body bgcolor="#FFFFFF">

<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_interface_lb.html">Next</a>&nbsp; |&nbsp; <a href="ug_interface.html">Previous</a></i></b></div>

<h2>
<a NAME="Initialization Functions"></a>General Interface Functions</h2>
Functions used to initialize and manipulate Zoltan's data structures are
described below:
<ul><b><a href="#Zoltan_Initialize">Zoltan_Initialize</a></b>
<br><b><a href="#Zoltan_Create">Zoltan_Create</a></b>
<br><b><a href="#Zoltan_Copy">Zoltan_Copy</a></b>
<br><b><a href="#Zoltan_Copy_To">Zoltan_Copy_To</a></b>
<br><b><a href="#Zoltan_Set_Param">Zoltan_Set_Param</a></b>
<br><b><a href="#Zoltan_Set_Param_Vec">Zoltan_Set_Param_Vec</a></b>
<br><b><a href="#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
<br><b><a href="#Zoltan_Set_Specific_Fn">Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn</a></b>
<br><b><a href="#Zoltan_Destroy">Zoltan_Destroy</a></b></ul>
<!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Initialize"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>C and C++:</td>

<td WIDTH="85%">int <b>Zoltan_Initialize</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int <i>argc</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; char **<i>argv</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; float *<i>ver</i>);</td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>

<td>FUNCTION <b>Zoltan_Initialize</b>( <i>argc</i>, <i>argv</i>,
<i>ver</i>)&nbsp;
<br>INTEGER(Zoltan_INT) :: Zoltan_Initialize&nbsp;
<br>INTEGER(Zoltan_INT), INTENT(IN), OPTIONAL :: argc&nbsp;
<br>CHARACTER(LEN=*), DIMENSION(*), INTENT(IN), OPTIONAL :: argv&nbsp;
<br>REAL(Zoltan_FLOAT), INTENT(OUT) :: ver&nbsp;</td>
</tr>

</table>

<hr WIDTH="100%">The <b>Zoltan_Initialize</b> function initializes MPI
for Zoltan. If the application uses MPI, this function should be called
after calling <b>MPI_Init</b>. If the application does not use MPI, this
function calls <b>MPI_Init</b> for use by Zoltan. This function is called
with the <i>argc</i> and <i>argv</i> command-line arguments from the main
program, which are used if <b>Zoltan_Initialize</b> calls <b>MPI_Init</b>.
From C,&nbsp; if <b>MPI_Init</b> has already been called, the <i>argc</i>
and <i>argv</i> arguments may have any value because their values will
be ignored.&nbsp; From Fortran, if one of <i>argc</i> or <i>argv</i> is
omitted, they must both be omitted. If they are omitted,
<i>ver</i> does
NOT have to be passed as a keyword argument.
<p><b>Zoltan_Initialize</b> returns the Zoltan version number so that
users can verify which version of the library their application is linked
to.
<p>C++ applications should call the C <B>Zoltan_Initialize</B> function
before using the C++ interface to the Zoltan library.  
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<td WIDTH="20%"><b>Arguments:</b></td>

<td WIDTH="80%">&nbsp;</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; argc</i></td>

<td>The number of command-line arguments to the application.</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; argv</i></td>

<td>An array of strings containing the command-line arguments to the application.</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; ver</i></td>

<td>Upon return, the version number of the library.</td>
</tr>

<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>

<td VALIGN=TOP><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
</table>

<p><!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Create"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>C:</td>

<td WIDTH="85%">struct <b>Zoltan_Struct</b> *<b>Zoltan_Create</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; MPI_Comm <i>communicator</i>);</td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>

<td>FUNCTION <b>Zoltan_Create</b>(<i>communicator</i>)&nbsp;
<br>TYPE(Zoltan_Struct), pointer :: Zoltan_Create&nbsp;
<br>INTEGER, INTENT(IN) :: communicator&nbsp;</td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>C++:</td>
<td WIDTH="85%"><b>Zoltan</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const MPI_Comm &<i>communicator</i> = MPI_COMM_WORLD);</td>
</tr>

</table>

<hr WIDTH="100%">The <b>Zoltan_Create</b> function allocates memory for
storage of information to be used by Zoltan and sets the default values
for the information. The pointer returned by this function is passed to
many subsequent functions. An application may allocate more than one <b>Zoltan_Struct</b>
data structure; for example, an application may use several <b>Zoltan_Struct</b>
structures if, say, it uses different decompositions with different load-balancing
techniques.
<p>
In the C++ interface to Zoltan, the <B>Zoltan</B> class represents
a Zoltan load balancing data structure and the functions that operate on it.
It is the constructor which allocates an instance of a <b>Zoltan</B> object.  It has
no return value.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<td WIDTH="20%"><b>Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; communicator</i></td>

<td>The MPI communicator to be used for this Zoltan structure. Only those
processors included in the communicator participate in Zoltan functions.
If all processors are to participate, <i>communicator</i> should be <b>MPI_COMM_WORLD</b>
.</td>
</tr>

<tr>
<td><b>Returned Value:&nbsp;</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; struct <b>Zoltan_Struct</b> *</td>

<td>Pointer to memory for storage of Zoltan information. If an error occurs,
NULL will be returned in C, or the result will be a nullified pointer in
Fortran. Any error that occurs in this function is assumed to be fatal.</td>
</tr>
</table>

<p><!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Copy"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>C:</td>

<td WIDTH="85%">struct <b>Zoltan_Struct</b> *<b>Zoltan_Copy</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b>Zoltan_Struct</b> *<i>from</i>);</td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>

<td>FUNCTION <b>Zoltan_Copy</b>(<i>from</i>)&nbsp;
<br>TYPE(Zoltan_Struct), pointer :: Zoltan_Copy&nbsp;
<br>TYPE(Zoltan_Struct), INTENT(IN) :: from &nbsp;</td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>C++:</td>
<td WIDTH="85%"><b>Zoltan</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const Zoltan &<i>zz</i>);</td>
</tr>

</table>

<hr WIDTH="100%">The <b>Zoltan_Copy</b> function creates a new
<b>Zoltan_Struct</b> and copies the state of the existing <b>Zoltan_Struct</b>,
which it has been passed, to the new structure.  It returns the new
<b>Zoltan_Struct</b>.
<p>
There is no direct interface to <B>Zoltan_Copy</B> from C++. Rather, the
<B>Zoltan</B> copy constructor invokes the C library <B>Zoltan_Copy</B>
program.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<td WIDTH="20%"><b>Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; from</i></td>

<td>A pointer to the <b>Zoltan_Struct</b> that is to be copied.
</td>
</tr>

<tr>
<td><b>Returned Value:&nbsp;</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; struct <b>Zoltan_Struct</b> *</td>

<td>Pointer to a new <b>Zoltan_Struct</b>, which is now a copy of <I>from</I>.
</td>
</tr>
</table>

<p><!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Copy_To"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>C:</td>

<td WIDTH="85%">int <b>Zoltan_Copy_To</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b>Zoltan_Struct</b> *<i>to</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b>Zoltan_Struct</b> *<i>from</i>);</td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>

<td>FUNCTION <b>Zoltan_Copy_To</b>(<i>to</i>, <i>from</i>)&nbsp;
<br>INTEGER(Zoltan_INT) :: Zoltan_Copy_To&nbsp;
<br>TYPE(Zoltan_Struct), INTENT(IN) :: to &nbsp;
<br>TYPE(Zoltan_Struct), INTENT(IN) :: from &nbsp;</td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>C++:</td>
<td WIDTH="85%"><b>Zoltan</b> & operator= (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const Zoltan &<i>zz</i>);</td>
</tr>

</table>

<hr WIDTH="100%">The <b>Zoltan_Copy_To</b> function copies one
<b>Zoltan_Struct</b> to another, after first freeing any memory used by the
target <b>Zoltan_Struct</b> and re-initializing it.  
<p>
The C++ interface to the <B>Zoltan_Copy_To</B> function is through the
<B>Zoltan</B> copy operator, which invokes the C library <B>Zoltan_Copy_To</B>
program.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<td WIDTH="20%"><b>Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; to</i></td>

<td>A pointer to an existing <b>Zoltan_Struct</b>, the target of the copy.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; from</i></td>

<td>A pointer to an existing <b>Zoltan_Struct</b>, the source of the copy.
</td>
</tr>

<tr>
<td><b>Returned Value:&nbsp;</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>

<td><b>0</b> on success and <b>1</b> on failure.
</td>
</tr>
</table>

<p><!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Set_Param"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>

<td WIDTH="85%">int <b>Zoltan_Set_Param</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; struct <b>Zoltan_Struct</b> *<i>zz</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; char *<i>param_name</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; char *<i>new_val</i>);</td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>

<td>FUNCTION <b>Zoltan_Set_Param</b>(<i>zz, param_name, new_val</i>)&nbsp;
<br>INTEGER(Zoltan_INT) :: Zoltan_Set_Param&nbsp;
<br>TYPE(Zoltan_Struct), INTENT(IN) :: zz&nbsp;
<br>CHARACTER(LEN=*), INTENT(IN) :: param_name, new_value&nbsp;</td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>

<td WIDTH="85%">int <b>Zoltan::Set_Param</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &<b>param_name</b>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &<b>new_value</b>);</td>
</tr>
</table>

<hr WIDTH="100%"><b>Zoltan_Set_Param</b> is used to alter the value of
one of the parameters used by Zoltan.&nbsp; All Zoltan parameters have
reasonable default values, but this routine allows a user to provide alternative
values if desired.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td><i>&nbsp;&nbsp;&nbsp; zz</i></td>

<td>Pointer to the Zoltan structure created by <b><a href="#Zoltan_Create">Zoltan_Create</a></b>.</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp; param_name</i></td>

<td>A string containing the name of the parameter to be altered.&nbsp;
Note that the string is case-insensitive.&nbsp; Also, different Zoltan
structures can have different parameter values.&nbsp;</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp; new_val</i></td>

<td>A string containing the new value for the parameter.&nbsp; Example
strings include "3.154", "True", "7" or anything appropriate for the parameter
being set. As above, the string is case-insensitive.&nbsp;</td>
</tr>

<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>

<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>

<tr>
<td></td>

<td></td>
</tr>

<tr>
<td></td>

<td></td>
</tr>
</table>
<!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Set_Param_Vec"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>

<td WIDTH="85%">int <b>Zoltan_Set_Param_Vec</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; struct <b>Zoltan_Struct</b> *<i>zz</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; char *<i>param_name</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; char *<i>new_val</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int <i>index</i>);</td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>

<td>FUNCTION <b>Zoltan_Set_Param_Vec</b>(<i>zz, param_name, new_val, index</i>)
<br>INTEGER(Zoltan_INT) :: Zoltan_Set_Param_Vec
<br>TYPE(Zoltan_Struct), INTENT(IN) :: zz
<br>CHARACTER(LEN=*), INTENT(IN) :: param_name, new_value
<br>INTEGER(Zoltan_INT), INTENT(IN) :: index</td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>

<td WIDTH="85%">int <b>Zoltan::Set_Param_Vec</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &<i>param_name</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &<i>new_val</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const int &<i>index</i>);</td>
</tr>
</table>

<hr WIDTH="100%"><b>Zoltan_Set_Param_Vec</b> is used to alter the value
of a vector parameter in Zoltan. A vector parameter is a parameter that
has one name but contains multiple values. These values are referenced
by their indices, usually starting at 0. Each entry (component) may have
a different value. This routine sets a single entry (component) of a vector
parameter. If you want all entries (components) of a vector parameter to
have the same value, set the parameter using <a href="#Zoltan_Set_Param">Zoltan_Set_Param</a>
as if it were a scalar parameter. If one only sets the values of a subset
of the indices for a vector parameter, the remaining entries will have
the default value for that particular parameter.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td><i>&nbsp;&nbsp;&nbsp; zz</i></td>

<td>Pointer to the Zoltan structure created by <b><a href="#Zoltan_Create">Zoltan_Create</a></b>.</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp; param_name</i></td>

<td>A string containing the name of the parameter to be altered.&nbsp;
Note that the string is case-insensitive.&nbsp; Also, different Zoltan
structures can have different parameter values.&nbsp;</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp; new_val</i></td>

<td>A string containing the new value for the parameter.&nbsp; Example
strings include "3.154", "True", "7" or anything appropriate for the parameter
being set. As above, the string is case-insensitive.&nbsp;</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp; index</i></td>

<td>The index of the entry of the vector parameter to be set. The default
in Zoltan is that the first entry in a vector has index 0 (C-style indexing).</td>
</tr>

<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>

<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
</table>
<!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Set_Fn"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>

<td WIDTH="85%">int <b>Zoltan_Set_Fn</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; struct <b>Zoltan_Struct *</b><i>zz</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b>ZOLTAN_FN_TYPE </b><i>fn_type</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void (*<i>fn_ptr</i>)(),
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void *<i>data</i>);</td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>

<td>FUNCTION <b>Zoltan_Set_Fn</b>(<i>zz, fn_type, fn_ptr, data</i>)&nbsp;
<br>INTEGER(Zoltan_INT) :: Zoltan_Set_Fn&nbsp;
<br>TYPE(Zoltan_Struct), INTENT(IN) :: zz&nbsp;
<br>TYPE(ZOLTAN_FN_TYPE), INTENT(IN) :: fn_type&nbsp;
<br>EXTERNAL :: fn_ptr&nbsp;
<br>&lt;<i>type-data</i>>, OPTIONAL :: data&nbsp;
<p>&lt;<i>type-data</i>> can be any of INTEGER(Zoltan_INT), DIMENSION(*)
or REAL(Zoltan_FLOAT), DIMENSION(*) or REAL(Zoltan_DOUBLE), DIMENSION(*)
or TYPE(Zoltan_User_Data_<i>x</i>) where <i>x</i> is 1, 2, 3 or 4. See
the section on
<a href="ug_fortran_api.html#fortran ug api query">Fortran
query functions</a> for an explanation.&nbsp;</td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>

<td WIDTH="85%">int <b>Zoltan::Set_Fn</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const <b>ZOLTAN_FN_TYPE </b> &<i>fn_type</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void (*<i>fn_ptr</i>)(),
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void *<i>data</i> = 0);</td>
</tr>
</table>

<hr WIDTH="100%"><b>Zoltan_Set_Fn</b> registers an application-supplied
query function in the Zoltan structure. All types of query functions can
be registered through calls to <b>Zoltan_Set_Fn</b>.&nbsp; To register
functions while maintaining strict type-checking of the <i>fn_ptr</i> argument,
use <b><a href="#Zoltan_Set_Specific_Fn">Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn</a></b>.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; zz</i></td>

<td>Pointer to the Zoltan structure created by
<b><a href="#Zoltan_Create">Zoltan_Create</a></b>.</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; fn_type</i></td>

<td>The type of function being registered; see <a href="ug_query.html#Application-Registered Query Functions">Application-Registered
Query Functions</a> for possible function types.</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; fn_ptr</i></td>

<td>A pointer to the application-supplied query function being registered.</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; data</i></td>

<td>A pointer to user defined data that will be passed, as an argument,
to the function pointed to by <i>fn_ptr</i>. In C it may be NULL. In Fortran
it may be omitted.</td>
</tr>

<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>

<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
</table>
<!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Set_Specific_Fn"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>

<td WIDTH="85%">int <b>Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; struct <b>Zoltan_Struct </b>*<i>zz</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;<b><i><a href="ug_query.html">zoltan_fn_type</a></i></b>>
(*<i>fn_ptr</i>)(),&nbsp;
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void *<i>data</i>);</td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>

<td>FUNCTION <b>Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn</b>(<i>zz, fn_ptr,
data</i>)&nbsp;
<br>INTEGER(Zoltan_INT) :: Zoltan_Set_&lt;<i><a href="ug_query.html">zoltan_fn_type</a></i>>_Fn&nbsp;
<br>TYPE(Zoltan_Struct), INTENT(IN) :: zz&nbsp;
<br>EXTERNAL :: fn_ptr&nbsp;
<br>&lt;<i>type-data</i>>, OPTIONAL :: data&nbsp;
<p>An interface block for <i>fn_ptr</i> is included in the FUNCTION definition
so that strict type-checking of the registered query function can be done.
<p>&lt;<i>type-data</i>> can be any of INTEGER(Zoltan_INT), DIMENSION(*)
or REAL(Zoltan_FLOAT), DIMENSION(*) or REAL(Zoltan_DOUBLE), DIMENSION(*)
or TYPE(Zoltan_User_Data_<i>x</i>) where <i>x</i> is 1, 2, 3 or 4. See
the section on
<a href="ug_fortran_api.html#fortran ug api query">Fortran
query functions</a> for an explanation.&nbsp;</td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>

<td WIDTH="85%">int <b>Zoltan::Set_&lt;<i>zoltan_fn_type</i>>_Fn</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;<b><i><a href="ug_query.html">zoltan_fn_type</a></i></b>>
(*<i>fn_ptr</i>)(),&nbsp;
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void *<i>data</i> = 0);</td>
</tr>
</table>

<hr WIDTH="100%">The interface functions <b>Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn</b>,
where <b>&lt;<i><a href="ug_query.html">zoltan_fn_type</a></i>></b> is
one of the query function types, register specific types of <a href="ug_query.html">application-supplied
query functions</a> in the Zoltan structure. One interface function exists
for each type of query function.&nbsp; For example, <b>Zoltan_Set_Num_Geom_Fn</b>
registers a query function of type <b><a href="ug_query_lb.html#ZOLTAN_NUM_GEOM_FN">ZOLTAN_NUM_GEOM_FN</a></b>.&nbsp;
Each query function has an associated <b>Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn</b>.&nbsp;
A complete list of these functions is included in <i>include/zoltan.h.</i>
<p>Query functions can be registered using either <b><a href="#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b>Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn</b>.
<br><b>Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn </b>provides strict type
checking of the <i>fn_ptr</i> argument; the argument's type is specified
for each
<b>Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn</b>. <b><a href="#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
does not provide this strict type checking, as the pointer to the registered
function is cast to a void pointer.
<table WIDTH="100%" NOSAVE >
<tr>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; zz</i></td>

<td>Pointer to the Zoltan structure created by
<b><a href="#Zoltan_Create">Zoltan_Create</a></b>.</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; fn_ptr</i></td>

<td>A pointer to the application-supplied query function being registered.&nbsp;
The type of the pointer matches &lt;<b><i><a href="ug_query.html">zoltan_fn_type</a></i></b>>
in the name <b>Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn</b>.</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; data</i></td>

<td>A pointer to user defined data that will be passed, as an argument,
to the function pointed to by <i>fn_ptr</i>. In C it may be NULL. In Fortran
it may be omitted.</td>
</tr>

<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>

<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>

<tr>
<td><b>Example:</b></td>

<td></td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP NOSAVE></td>

<td VALIGN=TOP NOSAVE>The interface function
<br>&nbsp;&nbsp;&nbsp; int <b>Zoltan_Set_Geom_Fn</b>(struct <b>Zoltan_Struct</b>
*zz, <b><a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN</a></b>
(*fn_ptr)(),
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
void *data);
<br>registers an <b><a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN</a></b>
query function.</td>
</tr>
</table>

<!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Destroy"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>

<td WIDTH="85%">void <b>Zoltan_Destroy</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; struct <b>Zoltan_Struct</b> **<i>zz</i>);</td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>

<td>SUBROUTINE <b>Zoltan_Destroy</b>(<i>zz</i>)&nbsp;
<br>TYPE(Zoltan_Struct), POINTER :: zz&nbsp;</td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>

<td WIDTH="85%">~<b>Zoltan</b> ();
</tr>
</table>

<hr WIDTH="100%"><b>Zoltan_Destroy</b> frees the memory associated with
a Zoltan structure and sets the structure to NULL in C or nullifies the
structure in Fortran. Note that <b>Zoltan_Destroy</b> does not deallocate
the import and export arrays returned from Zoltan (e.g., the arrays returned
from <b><a href="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>);
these arrays can be deallocated through a separate call to <b><a href="ug_interface_lb.html#Zoltan_LB_Free_Part">Zoltan_LB_Free_Part</a></b>.
<p>
There is no explicit <B>Destroy</B> method in the C++ interface.  The <B>Zoltan</B>
object is destroyed when the destructor executes.
<p>
As a side effect, <B>Zoltan_Destroy</B> (and the C++ <B>Zoltan</B>
destructor) frees the MPI communicator that
had been allocated for the structure.  So it is important that the
application does not call <B>MPI_Finalize</B> before it calls
<B>Zoltan_Destroy</B> or before the destructor executes.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; zz</i></td>

<td>A pointer to the address of the Zoltan structure, created by
<b><a href="ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>,
to be destroyed.&nbsp;</td>
</tr>
</table>
<!------------------------------------------------------------------------->
<p>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_interface_lb.html">Next:&nbsp;
Load-Balancing Functions</a>&nbsp; |&nbsp; <a href="ug_interface.html">Previous:&nbsp;
Zoltan Interface Functions</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>
